// ------------------------------------------------------------------
//			       CNS 185
//
//	    Documentation on how to use vector and matrix
// ------------------------------------------------------------------

// This is a combination of the example.cc files from the first two
// programming kits.  If you have already seen them, don't bother
// looking at this file.

// This file is written in the form of a legal C program.  Therefore
// all English text will be proceeded by a double slash at the head of
// this line, which signifies a comment to the compiler.

// The first thing to do is to include the specifications for vector
// and matrix objects, which are the header files "vector.hh" and
// "matrix.hh":
#include "vector.hh"
#include "matrix.hh"

// Include the standard input/output library for C so that we can
// print things out to the console
#include <stdio.h>

// Declare a function dummy() to demonstrate some of the operations
// you can perform on vectors and matrices:
dummy()
{
  // There are two ways to declare vectors.  The first is to
  // just give their dimension, in which case all elements will
  // be initialized to zero.  For example, x is two-dimensional,
  // z is three dimensional in the following declaration:
  vector x(2), z(3);

  // The second way is to provide a string constant with a list
  // of scalars separated by commas; the vector's dimension will
  // be determined by how many numbers are given and the vector's
  // elements will be set to the values given.  For example, y will
  // be the two-dimensional vector <2,3>:
  vector y("2, 3");

  // You can access the elements of the vector with square brackets
  // (for C programmers: it's just like accessing an array).
  x[0] = 1;   // Set the first element of x to 1
  x[1] = 4;   // Set the second element of x to 1

  // Print the second element of x, followed by a carriage return
  printf("%f\n", x[1]);

  // If you use illegal indices to access the vector, the computer
  // will complain with an error message at run time:
  x[5] = 4;   // ERROR! x only has two elements
  x[-1] = 4;  // ERROR! Indices can only be non-negative

  // All vector and matrix arithmetic are done with the normal
  // math operators: +, -, *, /, =, +=, -=, etc.  If you think
  // an operation can be accomplished, it probably can.

  y = x;      // Copy all of x's elements to y
  y = 3 * x;  // Do scalar/vector multiplication, assign to y

  x = x - 2 * y; // Vector arithmetic is very straightforward
  x += -2 * y;   // Does the same thing as last statement
  
  // NOTE: Dot product of vectors is NOT accomplished with the
  // * operator.  There is a separate function called "dot":
  double dot_product = dot(x, y);  // Take dot product of x and y

  // Arithmetic operations between vectors must be between vectors
  // of the same dimension; the computer will complain if they are not.
  y = x + z;  // ERROR! Tried to add 2-D and 3-D vectors

  // Just as there are two ways to declare vectors, there are two
  // ways to declare matrices that are analogous.  The first way is
  // to declare the rows and columns, and all elements will be set to 
  // zero.  Consider A, a 2x3 matrix (two rows, three columns):
  matrix A(2, 3);

  // The second way is to use a string.  Specify the row vectors as
  // numbers separated by commas, and separate the row vectors with
  // a semicolon.  Consider B, a 2x2 matrix which has the entries
  // |  1  -3 |
  // | -2   4 |
  matrix B("1, -3; -2, 4");

  // The square brackets operator used on a matrix references a row
  // vector, so A[0] is a vector representing the first row of A
  A[0] = z;     // Copy the values in 3-D vector z into first row of A

  // Using two square brackets accesses the individual scalar elements
  // of a matrix.  The second set of brackets accesses the element of
  // the row vector.  Once again, index range checking is performed and
  // run-time errors will be reported if indices are out of range.
  // A row index range error will result in a complaint and then
  // a segmentation fault.

  A[1][0] = 3;  // Set the element in the second row, first column to 3
  B[4][3] = 3;  // ERROR! Indices out of bounds

  // Arithmetic operations are defined for matrices too: adding matrices,
  // multiplying them, adding and multiplying by scalars.  But like vectors,
  // you must make sure you are performing operations between matrices
  // of compatible sizes or run-time errors will result.

  y = A * x;  // Multiply A by x and assign result to y
  A += B;     // ERROR! Matrices must be of same size to add them
}

// Below is an example of a function operating on a vector.  It takes
// a vector as input, adds a given number to each element, and returns
// the result.  Note that the vector is passed by value, and just like
// any other pass by value in C, a call to the function like:
//
// some_vector = add_to_elements(other_vector, 2);
//
// will not affect the values of "other_vector."  If you want to affect
// the values of "other_vector," you should pass it by reference (using
// a pointer -- but this is an advanced C topic which you will not need).

// Note the ANSI standard method for declaring function parameters.  This
// is REQUIRED by the GNU compiler.  Do NOT use the traditional method
// of declaring parameter types after the function prototype.

vector add_to_elements(vector v, double add_me)
{
  int i;

  // The notation v.dimension() means "dimension of vector v."  Therefore
  // this routine will handle a vector of any dimension.
  for (i = 0; i < v.dimension(); i++)
    v[i] += add_me;

  // Return the result of the function.  You can treat vectors just like
  // any other data type; return them just as you would an "int" or a 
  // "double" result.
  return v;
}


// Next, declare a function called main() which will use
// add_to_elements and also show off some of the input/output features
// of C++.  All C programs must have a main() procedure since it is
// the first procedure to be executed in the program.
main()
{
  // First, print out the message to the console.  "cout" stands for
  // "character output," in other words, the console.  The "<<"
  // operator means "send to".  So this next line means send the
  // string "Please enter..." to the console:
  cout << "Please enter a vector (numbers separated by commas): ";

  // Declare an object of type string.  This is an object type you
  // haven't seen before, but it is useful for text processing.
  // We will be using it to get a string from the user.
  string s;

  // "cin" stands for "character input" (i.e., the keyboard).  So this
  // next line means "collect a string from the user."  It will take
  // input until the user hits RETURN.
  cin >> s;

  // Next we can make a vector based on that string.  v's value will
  // be set by the entries in s.
  vector v(s);

  // Now we want a number from the user.
  cout << "Please enter a number: ";

  // Let's get the number
  double n;
  cin >> n;

  // Next, let's use our function above to add the number n to each
  // of the elements of the vector.  First we must make a vector to
  // put the result into.  We'll create a vector w based on v:
  vector w(v.dimension());

  // Next, actually call the function.  After the function call,
  // v and n remain unchanged, but w is set by the return value
  w = add_to_elements(v, n);

  // Now let's let the user know about the results.  Note that you
  // can chain together things to send to cout with a series of
  // "<<" operators.  Also note the command "v.to_string()" which
  // converts v into a string for printing out.
  cout << "The result of adding " << n << " to {" << v.to_string()
    << "} is {" << w.to_string() << "}\n";
}